react-paginate

What is react-paginate?

react-paginate is a React component that helps in creating pagination for your data. It provides a flexible and customizable way to paginate through large sets of data, making it easier to navigate and manage.

What are react-paginate's main functionalities?

Basic Pagination

This code demonstrates a basic usage of react-paginate. It sets up a pagination component with labels for previous and next buttons, a break label, and specifies the number of pages to display. The handlePageClick function logs the selected page number.

import ReactPaginate from 'react-paginate';

function PaginationComponent() {
  const handlePageClick = (data) => {
    console.log(data.selected);
  };

  return (
    <ReactPaginate
      previousLabel={'previous'}
      nextLabel={'next'}
      breakLabel={'...'}
      breakClassName={'break-me'}
      pageCount={10}
      marginPagesDisplayed={2}
      pageRangeDisplayed={5}
      onPageChange={handlePageClick}
      containerClassName={'pagination'}
      subContainerClassName={'pages pagination'}
      activeClassName={'active'}
    />
  );
}

Custom Styling

This example shows how to apply custom styling to the pagination component by importing a CSS file and setting custom class names for the container, sub-container, and active page.

import ReactPaginate from 'react-paginate';
import './pagination.css';

function CustomStyledPagination() {
  const handlePageClick = (data) => {
    console.log(data.selected);
  };

  return (
    <ReactPaginate
      previousLabel={'previous'}
      nextLabel={'next'}
      breakLabel={'...'}
      breakClassName={'break-me'}
      pageCount={10}
      marginPagesDisplayed={2}
      pageRangeDisplayed={5}
      onPageChange={handlePageClick}
      containerClassName={'custom-pagination'}
      subContainerClassName={'pages custom-pagination'}
      activeClassName={'active'}
    />
  );
}

Controlled Pagination

This example demonstrates a controlled pagination component where the current page state is managed using React's useState hook. The forcePage prop is used to control the current page programmatically.

import React, { useState } from 'react';
import ReactPaginate from 'react-paginate';

function ControlledPagination() {
  const [currentPage, setCurrentPage] = useState(0);

  const handlePageClick = (data) => {
    setCurrentPage(data.selected);
  };

  return (
    <div>
      <ReactPaginate
        previousLabel={'previous'}
        nextLabel={'next'}
        breakLabel={'...'}
        breakClassName={'break-me'}
        pageCount={10}
        marginPagesDisplayed={2}
        pageRangeDisplayed={5}
        onPageChange={handlePageClick}
        containerClassName={'pagination'}
        subContainerClassName={'pages pagination'}
        activeClassName={'active'}
        forcePage={currentPage}
      />
      <p>Current Page: {currentPage + 1}</p>
    </div>
  );
}

Other packages similar to react-paginate

rc-pagination

rc-pagination is a pagination component for React that provides a similar set of features to react-paginate. It is highly customizable and supports various pagination styles. Compared to react-paginate, rc-pagination offers more built-in styles and configurations but may require more setup for custom designs.

react-js-pagination

react-js-pagination is another React pagination component that offers a straightforward API for implementing pagination. It is simpler than react-paginate and may be easier to use for basic pagination needs. However, it might lack some of the advanced customization options available in react-paginate.

material-ui-pagination

material-ui-pagination is a pagination component designed to work seamlessly with Material-UI. It provides a Material Design look and feel, making it a good choice for projects already using Material-UI. Compared to react-paginate, it offers a more integrated experience with Material-UI but may not be as flexible for non-Material-UI projects.

README

react-paginate

A ReactJS component to render a pagination.

By installing this component and writing only a little bit of CSS you can obtain this: Note: You should write your own css to obtain this UI. This package do not provide any css.

or

Installation

Install react-paginate with npm:

npm install react-paginate --save

Usage

import React, { useEffect, useState } from 'react';
import ReactDOM from 'react-dom';
import ReactPaginate from 'react-paginate';

// Example items, to simulate fetching from another resources.
const items = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14];

function Items({ currentItems }) {
  return (
    <>
      {currentItems &&
        currentItems.map((item) => (
          <div>
            <h3>Item #{item}</h3>
          </div>
        ))}
    </>
  );
}

function PaginatedItems({ itemsPerPage }) {
  // We start with an empty list of items.
  const [currentItems, setCurrentItems] = useState(null);
  const [pageCount, setPageCount] = useState(0);
  // Here we use item offsets; we could also use page offsets
  // following the API or data you're working with.
  const [itemOffset, setItemOffset] = useState(0);

  useEffect(() => {
    // Fetch items from another resources.
    const endOffset = itemOffset + itemsPerPage;
    console.log(`Loading items from ${itemOffset} to ${endOffset}`);
    setCurrentItems(items.slice(itemOffset, endOffset));
    setPageCount(Math.ceil(items.length / itemsPerPage));
  }, [itemOffset, itemsPerPage]);

  // Invoke when user click to request another page.
  const handlePageClick = (event) => {
    const newOffset = (event.selected * itemsPerPage) % items.length;
    console.log(
      `User requested page number ${event.selected}, which is offset ${newOffset}`
    );
    setItemOffset(newOffset);
  };

  return (
    <>
      <Items currentItems={currentItems} />
      <ReactPaginate
        breakLabel="..."
        nextLabel="next >"
        onPageChange={handlePageClick}
        pageRangeDisplayed={5}
        pageCount={pageCount}
        previousLabel="< previous"
        renderOnZeroPageCount={null}
      />
    </>
  );
}

// Add a <div id="container"> to your HTML to see the componend rendered.
ReactDOM.render(
  <PaginatedItems itemsPerPage={4} />,
  document.getElementById('container')
);

Test it on CodePen.

You can also read the code of demo/js/demo.js to quickly understand how to make react-paginate work with a list of objects.

You can also check this CodePen demo with fetching sample code (using GitHub API) and synchronized pagination widgets.

Props

Name	Type	Description
pageCount	Number	Required. The total number of pages.
pageRangeDisplayed	Number	Required. The range of pages displayed.
marginPagesDisplayed	Number	Required. The number of pages to display for margins.
previousLabel	Node	Label for the previous button.
nextLabel	Node	Label for the next button.
breakLabel	Node	Label for ellipsis.
breakClassName	String	The classname on tag li of the ellipsis element.
breakLinkClassName	String	The classname on tag a of the ellipsis element.
onPageChange	Function	The method to call when a page is clicked. Exposes the current page object as an argument.
onPageActive	Function	The method to call when an active page is clicked. Exposes the active page object as an argument.
initialPage	Number	The initial page selected, in uncontrolled mode. Do not use with forcePage at the same time.
forcePage	Number	To override selected page with parent prop. Use this if you want to control the page from your app state.
disableInitialCallback	boolean	Disable onPageChange callback with initial page. Default: false
containerClassName	String	The classname of the pagination container.
className	String	Same as containerClassName. For use with styled-components & other CSS-in-JS.
pageClassName	String	The classname on tag li of each page element.
pageLinkClassName	String	The classname on tag a of each page element.
pageLabelBuilder	Function	Function to set the text on page links. Defaults to (page) => page
activeClassName	String	The classname for the active page.
activeLinkClassName	String	The classname on the active tag a.
previousClassName	String	The classname on tag li of the previous button.
nextClassName	String	The classname on tag li of the next button.
previousLinkClassName	String	The classname on tag a of the previous button.
nextLinkClassName	String	The classname on tag a of the next button.
disabledClassName	String	The classname for disabled previous and next buttons.
hrefBuilder	Function	The method is called to generate the href attribute value on tag a of each page element.
extraAriaContext	String	DEPRECATED: Extra context to add to the aria-label HTML attribute.
ariaLabelBuilder	Function	The method is called to generate the aria-label attribute value on each page link
eventListener	String	The event to listen onto before changing the selected page. Default is: onClick.
renderOnZeroPageCount	Function	A render fonction called when pageCount is zero. Let the Previous / Next buttons displayed by default (undefined). Display nothing when null is provided.

Demo

To run the demo locally, clone the repository and move into it:

git clone [e-mail]:AdeleD/react-paginate.git
cd react-paginate

Install dependencies:

make install

Prepare the demo:

make demo

Run the server:

make serve

Open your browser and go to http://localhost:3000/

Contribute

1. Submit an issue
2. Fork the repository
3. Create a dedicated branch (never ever work in master)
4. Run npm start http://localhost:3000
5. Fix bugs or implement features
6. Always write tests
7. Format with Prettier npm run format and check ESLint npm run lint

Run tests:

make test

Changelog

= 7.1.5

• Fix the Webpack build to work for both browser and Node (see: https://github.com/AdeleD/react-paginate/issues/389)
• Add a warning when providing both initialPage and forcePage props. You should only provides forcePage when the component is controlled. (see: https://github.com/AdeleD/react-paginate/pull/290)